Skip to content

docs: add CustomHealth Lua authoring guide - #617

Merged
michaeljguarino merged 4 commits into
mainfrom
agent/custom-health-lua-guide-1786633728116
Aug 13, 2026
Merged

docs: add CustomHealth Lua authoring guide#617
michaeljguarino merged 4 commits into
mainfrom
agent/custom-health-lua-guide-1786633728116

Conversation

@plural-copilot

@plural-copilot plural-copilot Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add an example-first CustomHealth Lua authoring guide under Continuous Deployment > The deployment operator.
  • Document only the verified manifest, obj, healthStatus, allowed-status, and supported-helper contract.
  • Add the navigation entry and generated route index.

Validation

  • docker run --rm -v "$PWD":/app -w /app node:22-alpine sh -lc 'apk add --no-cache git >/dev/null && git config --global --add safe.directory /app && corepack enable && yarn generate:route-index'
  • docker run --rm -v "$PWD":/app -w /app node:22-alpine sh -lc 'apk add --no-cache git >/dev/null && git config --global --add safe.directory /app && corepack enable && yarn lint' — passed with 13 existing CSS compatibility warnings and no errors.
  • docker run --rm -v "$PWD":/app -w /app node:22-alpine sh -lc 'apk add --no-cache git >/dev/null && git config --global --add safe.directory /app && corepack enable && yarn build' — passed.

Supersedes #616

This is a clean replacement PR created on a new branch, focused on authoring CustomHealth Lua. It intentionally excludes unsupported implementation claims, including sandboxing, standard-library availability, precedence, namespace semantics, controller mechanics, and detailed error behavior.

Plural Flow: docs
Plural Preview: docs

@plural-copilot
plural-copilot Bot requested a review from a team as a code owner August 13, 2026 15:09

@plural-copilot plural-copilot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR was generated by the codex Plural Agent Runtime. Here's some useful information you might want to know to evaluate the ai's perfomance:

Name Details
💬 Prompt Create a new clean replacement PR in this repository for CustomHealth docs. It must explicitly supersede the closed prior PR #616; do not reuse or iterate on that branch/PR. Inspect #616 if accessible only for context and ensure the new PR is focused and does not carry forward unverified claims....
🔗 Run history View run history

@greptile-apps

greptile-apps Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

Adds an example-first guide for authoring deployment-operator CustomHealth Lua scripts and registers it in documentation navigation and generated routes.

  • Documents the CustomHealth manifest and Lua input/output contract.
  • Lists supported health statuses and helper functions.
  • Adds the new page beneath the deployment-operator section.

Confidence Score: 4/5

The documentation should not merge until the Lua input global is corrected, because copying the primary example currently produces a runtime script failure.

The guide consistently dereferences lowercase obj, but the operator registers uppercase Obj; Lua identifiers are case-sensitive, so the documented script indexes nil before assigning healthStatus.

Files Needing Attention: pages/plural-features/continuous-deployment/deployment-operator/custom-health.md

Important Files Changed

Filename Overview
pages/plural-features/continuous-deployment/deployment-operator/custom-health.md Adds the authoring guide, but its example and prose use a case-sensitive Lua input global that differs from the operator runtime.
src/routing/docs-structure.ts Adds the new guide to the deployment-operator navigation using the expected path and nesting.
generated/routes.json Adds a generated route whose path and markdown target match the new page.

Reviews (1): Last reviewed commit: "docs: add CustomHealth Lua authoring gui..." | Re-trigger Greptile

version: v1
kind: Widget
script: |
-- obj is the target Kubernetes resource.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Lowercase global breaks Lua scripts

When a user copies this example, the script dereferences lowercase obj, but the deployment operator exposes the resource as uppercase Obj; Lua therefore indexes a nil global and fails before assigning healthStatus.

@michaeljguarino

Copy link
Copy Markdown
Member

A few improvments:

  1. The example customhealthobject should be:
apiVersion: deployments.plural.sh/v1alpha1
kind: CustomHealth
metadata:
  name: example-ready-condition
  namespace: <namespace>
spec:
  group: example.io
  version: v1
  kind: Example
  script: |
    healthStatus = { status = "Unknown" }

    if Obj.status ~= nil and statusConditionExists(Obj.status, "Ready") then
      healthStatus = { status = "Progressing" }
      if isStatusConditionTrue(Obj.status, "Ready") then
        healthStatus = { status = "Healthy" }
      end
    end
  1. The correct built-in functions are referenced there statusConditionExists isStatusConditionTrue, etc. We should document each explicitly.
  2. We should document the expected status values, again based on this
  3. We should explain this is a deployment-operator api, so needs to be placed on each cluster it should be applied to, ideally via a global service.

@plural-copilot plural-copilot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔧 Deploy preview for docs-pr-617 is building...

Name Details
⚡ Service docs-pr-617 (4 / 5 ready)
☁️ Cluster plural (eks)
:octocat: Commit sha e7793c4
Plural URL https://console.mgmt.plural.sh/cd/clusters/446acdef-8524-425a-a49f-5336a...
🔍 Logs URL https://console.mgmt.plural.sh/cd/clusters/446acdef-8524-425a-a49f-5336a...
🌊 Flow URL https://console.mgmt.plural.sh/flows/08a17af1-8578-449e-9ae1-28ccd97eafc...
Preview Link Preview

You can learn more about preview environments and Plural Flows here


`CustomHealth` is a deployment-operator API, so apply it to each cluster where it should be used. To distribute the same resource across a fleet, use a [GlobalService](/plural-features/continuous-deployment/global-service).

Start with a complete manifest. This example targets `example.io/v1`, `Example` resources and evaluates their `Ready` condition.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit clunky, just introduce this as "Here's an example manifest:"

kind: CustomHealth
metadata:
name: example-ready-condition
namespace: <namespace>

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't include namespace

end
```

Set `metadata.name` and `metadata.namespace` for the `CustomHealth` resource. Set `spec.group`, `spec.kind`, and, when needed, the optional `spec.version` to identify the target GVK. Put the Lua code in `spec.script`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't explain you need to set metadata.name/namespace, that's true for every k8s resource.

@michaeljguarino
michaeljguarino merged commit abc286a into main Aug 13, 2026
12 checks passed
@michaeljguarino
michaeljguarino deleted the agent/custom-health-lua-guide-1786633728116 branch August 13, 2026 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant